*
*/
+/**
+ * SECTION:ostree-sign
+ * @title: Signature management
+ * @short_description: Sign and verify commits
+ *
+ * An #OstreeSign interface allows to select and use any available engine
+ * for signing or verifying the commit object or summary file.
+ */
+
#include "config.h"
#include <unistd.h>
g_debug ("OstreeSign initialization");
}
-const gchar * ostree_sign_metadata_key (OstreeSign *self)
+/**
+ * ostree_sign_metadata_key:
+ * @self: an #OstreeSign object
+ *
+ * Return the pointer to the name of the key used in (detached) metadata for
+ * current signing engine.
+ *
+ * Returns: (transfer none): pointer to the metadata key name,
+ * @NULL in case of error (unlikely).
+ *
+ * Since: 2020.2
+ */
+const gchar *
+ostree_sign_metadata_key (OstreeSign *self)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->metadata_key (self);
}
-const gchar * ostree_sign_metadata_format (OstreeSign *self)
+/**
+ * ostree_sign_metadata_format:
+ * @self: an #OstreeSign object
+ *
+ * Return the pointer to the string with format used in (detached) metadata for
+ * current signing engine.
+ *
+ * Returns: (transfer none): pointer to the metadata format,
+ * @NULL in case of error (unlikely).
+ *
+ * Since: 2020.2
+ */
+const gchar *
+ostree_sign_metadata_format (OstreeSign *self)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->metadata_format (self);
}
-gboolean ostree_sign_clear_keys (OstreeSign *self,
- GError **error)
+/**
+ * ostree_sign_clear_keys:
+ * @self: an #OstreeSign object
+ * @error: a #GError
+ *
+ * Clear all previously preloaded secret and public keys.
+ *
+ * Returns: @TRUE in case if no errors, @FALSE in case of error
+ *
+ * Since: 2020.2
+ */
+gboolean
+ostree_sign_clear_keys (OstreeSign *self,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->clear_keys (self, error);
}
-gboolean ostree_sign_set_sk (OstreeSign *self,
- GVariant *secret_key,
- GError **error)
+/**
+ * ostree_sign_set_sk:
+ * @self: an #OstreeSign object
+ * @secret_key: secret key to be added
+ * @error: a #GError
+ *
+ * Set the secret key to be used for signing data, commits and summary.
+ *
+ * The @secret_key argument depends of the particular engine implementation.
+ *
+ * Returns: @TRUE in case if the key could be set successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
+gboolean
+ostree_sign_set_sk (OstreeSign *self,
+ GVariant *secret_key,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->set_sk (self, secret_key, error);
}
-gboolean ostree_sign_set_pk (OstreeSign *self,
- GVariant *public_key,
- GError **error)
+/**
+ * ostree_sign_set_pk:
+ * @self: an #OstreeSign object
+ * @public_key: single public key to be added
+ * @error: a #GError
+ *
+ * Set the public key for verification. It is expected what all
+ * previously pre-loaded public keys will be dropped.
+ *
+ * The @public_key argument depends of the particular engine implementation.
+ *
+ * Returns: @TRUE in case if the key could be set successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
+gboolean
+ostree_sign_set_pk (OstreeSign *self,
+ GVariant *public_key,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->set_pk (self, public_key, error);
}
-gboolean ostree_sign_add_pk (OstreeSign *self,
- GVariant *public_key,
- GError **error)
+/**
+ * ostree_sign_add_pk:
+ * @self: an #OstreeSign object
+ * @public_key: single public key to be added
+ * @error: a #GError
+ *
+ * Add the public key for verification. Could be called multiple times for
+ * adding all needed keys to be used for verification.
+ *
+ * The @public_key argument depends of the particular engine implementation.
+ *
+ * Returns: @TRUE in case if the key could be added successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
+gboolean
+ostree_sign_add_pk (OstreeSign *self,
+ GVariant *public_key,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->add_pk (self, public_key, error);
}
-/* Load private keys for verification from anywhere.
- * No need to have the same function for secret keys -- the signing SW must do it in it's own way
- * */
+/**
+ * ostree_sign_load_pk:
+ * @self: an #OstreeSign object
+ * @options: any options
+ * @error: a #GError
+ *
+ * Load public keys for verification from anywhere.
+ * It is expected that all keys would be added to already pre-loaded keys.
+ *
+ * The @options argument depends of the particular engine implementation.
+ *
+ * For example, @ed25515 engine could use following string-formatted options:
+ * - @filename -- single file to use to load keys from
+ * - @basedir -- directory containing subdirectories
+ * 'trusted.ed25519.d' and 'revoked.ed25519.d' with appropriate
+ * public keys. Used for testing and re-definition of system-wide
+ * directories if defaults are not suitable for any reason.
+ *
+ * Returns: @TRUE in case if at least one key could be load successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
+/*
+ * No need to have similar function for secret keys load -- it is expected
+ * what the signing software will load the secret key in it's own way.
+ */
gboolean
ostree_sign_load_pk (OstreeSign *self,
GVariant *options,
return OSTREE_SIGN_GET_IFACE (self)->load_pk (self, options, error);
}
-gboolean ostree_sign_data (OstreeSign *self,
- GBytes *data,
- GBytes **signature,
- GCancellable *cancellable,
- GError **error)
+/**
+ * ostree_sign_data:
+ * @self: an #OstreeSign object
+ * @data: the raw data to be signed with pre-loaded secret key
+ * @signature: in case of success will contain signature
+ * @cancellable: A #GCancellable
+ * @error: a #GError
+ *
+ * Sign the given @data with pre-loaded secret key.
+ *
+ * Depending of the signing engine used you will need to load
+ * the secret key with #ostree_sign_set_sk.
+ *
+ * Returns: @TRUE if @data has been signed successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
+gboolean
+ostree_sign_data (OstreeSign *self,
+ GBytes *data,
+ GBytes **signature,
+ GCancellable *cancellable,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
return OSTREE_SIGN_GET_IFACE (self)->data (self, data, signature, cancellable, error);
}
+/**
+ * ostree_sign_data_verify:
+ * @self: an #OstreeSign object
+ * @data: the raw data to check
+ * @signatures: the signatures to be checked
+ * @error: a #GError
+ *
+ * Verify given data against signatures with pre-loaded public keys.
+ *
+ * Depending of the signing engine used you will need to load
+ * the public key(s) with #ostree_sign_set_pk, #ostree_sign_add_pk
+ * or #ostree_sign_load_pk.
+ *
+ * Returns: @TRUE if @data has been signed at least with any single valid key,
+ * @FALSE in case of error or no valid keys are available (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
gboolean
ostree_sign_data_verify (OstreeSign *self,
- GBytes *data,
- GVariant *signatures,
- GError **error)
+ GBytes *data,
+ GVariant *signatures,
+ GError **error)
{
g_debug ("%s enter", __FUNCTION__);
g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE);
return g_variant_dict_end (&metadata_dict);
}
+/**
+ * ostree_sign_commit_verify:
+ * @self: an #OstreeSign object
+ * @repo: an #OsreeRepo object
+ * @commit_checksum: SHA256 of given commit to verify
+ * @cancellable: A #GCancellable
+ * @error: a #GError
+ *
+ * Verify if commit is signed with known key.
+ *
+ * Depending of the signing engine used you will need to load
+ * the public key(s) for verification with #ostree_sign_set_pk,
+ * #ostree_sign_add_pk and/or #ostree_sign_load_pk.
+ *
+ * Returns: @TRUE if commit has been verified successfully,
+ * @FALSE in case of error or no valid keys are available (@error will contain the reason).
+ *
+ * Since: 2020.2
+ */
gboolean
ostree_sign_commit_verify (OstreeSign *self,
OstreeRepo *repo,
return ostree_sign_data_verify (self,
- signed_data,
- signatures,
- error);
+ signed_data,
+ signatures,
+ error);
}
-const gchar * ostree_sign_get_name (OstreeSign *self)
+/**
+ * ostree_sign_get_name:
+ * @self: an #OstreeSign object
+ *
+ * Return the pointer to the name of currently used/selected signing engine.
+ *
+ * The list of available engines could be acquired with #ostree_sign_list_names.
+ *
+ * Returns: (transfer none): pointer to the name
+ * @NULL in case of error (unlikely).
+ *
+ * Since: 2020.2
+ */
+const gchar *
+ostree_sign_get_name (OstreeSign *self)
{
g_debug ("%s enter", __FUNCTION__);
- g_return_val_if_fail (OSTREE_IS_SIGN (self), FALSE);
- g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, FALSE);
+ g_return_val_if_fail (OSTREE_IS_SIGN (self), NULL);
+ g_return_val_if_fail (OSTREE_SIGN_GET_IFACE (self)->get_name != NULL, NULL);
return OSTREE_SIGN_GET_IFACE (self)->get_name (self);
}
-OstreeSign * ostree_sign_get_by_name (const gchar *name, GError **error)
-{
- g_debug ("%s enter", __FUNCTION__);
-
- OstreeSign *sign = NULL;
-
- /* Get types if not initialized yet */
-#if defined(HAVE_LIBSODIUM)
- if (sign_types[SIGN_ED25519].type == 0)
- sign_types[SIGN_ED25519].type = OSTREE_TYPE_SIGN_ED25519;
-#endif
- if (sign_types[SIGN_DUMMY].type == 0)
- sign_types[SIGN_DUMMY].type = OSTREE_TYPE_SIGN_DUMMY;
-
- for (gint i=0; i < G_N_ELEMENTS(sign_types); i++)
- {
- if (g_strcmp0 (name, sign_types[i].name) == 0)
- {
- g_debug ("Found '%s' signing module", sign_types[i].name);
- sign = g_object_new (sign_types[i].type, NULL);
- break;
- }
- }
-
- if (sign == NULL)
- g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
- "Requested signature type is not implemented");
-
- return sign;
-}
-
-
/**
* ostree_sign_commit:
- * @self: Self
+ * @self: an #OstreeSign object
+ * @repo: an #OsreeRepo object
* @commit_checksum: SHA256 of given commit to sign
* @cancellable: A #GCancellable
* @error: a #GError
*
- * Add a GPG signature to a commit.
+ * Add a signature to a commit.
+ *
+ * Depending of the signing engine used you will need to load
+ * the secret key with #ostree_sign_set_sk.
+ *
+ * Returns: @TRUE if commit has been signed successfully,
+ * @FALSE in case of error (@error will contain the reason).
+ *
+ * Since: 2020.2
*/
gboolean
ostree_sign_commit (OstreeSign *self,
return TRUE;
}
-GStrv ostree_sign_list_names(void)
+/**
+ * ostree_sign_list_names:
+ *
+ * Return an array with all available sign engines names.
+ *
+ * Returns: (transfer full): an array of strings, free when you used it
+ *
+ * Since: 2020.2
+ */
+GStrv
+ostree_sign_list_names(void)
{
g_debug ("%s enter", __FUNCTION__);
for (i=0; i < G_N_ELEMENTS(sign_types); i++)
{
names[i] = g_strdup(sign_types[i].name);
- g_debug ("Found '%s' signing module", names[i]);
+ g_debug ("Found '%s' signing engine", names[i]);
}
return names;
}
+
+/**
+ * ostree_sign_get_by_name:
+ * @name: the name of desired signature engine
+ * @error: return location for a #GError
+ *
+ * Tries to find and return proper signing engine by it's name.
+ *
+ * The list of available engines could be acquired with #ostree_sign_list_names.
+ *
+ * Returns: (transfer full): a constant, free when you used it
+ *
+ * Since: 2020.2
+ */
+OstreeSign *
+ostree_sign_get_by_name (const gchar *name, GError **error)
+{
+ g_debug ("%s enter", __FUNCTION__);
+
+ OstreeSign *sign = NULL;
+
+ /* Get types if not initialized yet */
+#if defined(HAVE_LIBSODIUM)
+ if (sign_types[SIGN_ED25519].type == 0)
+ sign_types[SIGN_ED25519].type = OSTREE_TYPE_SIGN_ED25519;
+#endif
+ if (sign_types[SIGN_DUMMY].type == 0)
+ sign_types[SIGN_DUMMY].type = OSTREE_TYPE_SIGN_DUMMY;
+
+ for (gint i=0; i < G_N_ELEMENTS(sign_types); i++)
+ {
+ if (g_strcmp0 (name, sign_types[i].name) == 0)
+ {
+ g_debug ("Using '%s' signing engine", sign_types[i].name);
+ sign = g_object_new (sign_types[i].type, NULL);
+ break;
+ }
+ }
+
+ if (sign == NULL)
+ g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
+ "Requested signature type is not implemented");
+
+ return sign;
+}
projects / ostree.git / commitdiff